﻿// --------------------------------------------------------------------------------------------------------------------
// <copyright file="IEventBinder.cs" company="JDML Consulting Ltd.">
//   Copyright 2011 Photon Project - http://photon.codeplex.com
// </copyright>
// <summary>
//   Defines the IEventBinder type.
// </summary>
// --------------------------------------------------------------------------------------------------------------------

namespace Photon
{
    using System;

    /// <summary>
    /// Provides a mechanism for managing event subscriptions.
    /// </summary>
    public interface IEventBinder
    {
        /// <summary>
        /// Get the name of the event the <see cref="IEventBinder"/> binds to on the <see cref="PublisherType"/>
        /// </summary>
        string EventName { get; }

        /// <summary>
        /// Gets the type that declares the event the <see cref="IEventBinder"/> binds to.
        /// </summary>
        Type PublisherType { get; }

        /// <summary>
        /// Gets the type of the event.
        /// </summary>
        /// <value>The type of the event.</value>
        Type EventType { get; }

        /// <summary>
        /// Adds an event subscription on the specified <paramref name="publisher"/>
        /// </summary>
        /// <param name="publisher">The publisher of the event.</param>
        /// <param name="handler">The event handler.</param>
        /// <returns>A subscription token object that can be used identify the subsciption (may be null), the token should be passed to <see cref="Remove"/>.</returns>
        object Add(object publisher, Delegate handler);

        /// <summary>
        /// Removes an event subscription on the specified <paramref name="publisher"/>
        /// </summary>
        /// <param name="publisher">The publisher of the event.</param>
        /// <param name="subscriptionToken">The subscription token (if any) returned by the corresponding add operation.</param>
        /// <param name="handler">The event handler.</param>
        void Remove(object publisher, object subscriptionToken, Delegate handler);
    }

    /// <summary>
    /// Provides a strongly typed mechanism for managing event subscriptions.
    /// </summary>
    /// <typeparam name="TPublisher">The type of the publisher.</typeparam>
    /// <typeparam name="TDelegate">The type of the delegate.</typeparam>
    public interface IEventBinder<in TPublisher, TDelegate> : IEventBinder where TDelegate : class
    {
        object Add(TPublisher publisher, TDelegate handler);
        void Remove(TPublisher publisher, object subscriptionToken, TDelegate handler);
    }
}